The VideoToolbox is a collection of two hundred C subroutines and several demo and utility programs that I and others have written to do visual psychophysics with Macintosh computers. It is fully compatible with 680x0 and Power PC Macs and Symantec THINK C 7 and Metrowerks CodeWarrior C 4.5 compilers. It's free and may not be sold without permission. It should be useful to anyone who wants to present accurately specified visual stimuli or use the Mac for psychometric experiments. The text file "Video synch" discusses all the ways of synchronizing programs to video displays and the many pitfalls to avoid. The TimeVideo application checks out the timing of all video devices in anticipation of their use in critical real-time applications, e.g. movies or lookup table animation. Low-level routines control video timing and lookup tables, display real-time movies, and implement the luminance-control algorithms suggested by Pelli and Zhang (1991). In particular, GetPixelsQuickly and SetPixelsQuickly peek and poke pixels in bitmaps and pixmaps, CopyBitsQuickly and CopyWindows faithfully copy between bit/pixmaps and the screen, WindowToEPS saves an image to disk, and SetEntriesQuickly and GDSetEntries load the screen's color lookup table, all without any of QuickDraw's color translations. High-level routines help analyze psychophysical experiments (e.g. graphing or maximum-likelihood fitting of psychometric data). Assign.c is a runtime C interpreter for C assignment statements, which is useful for controlling experiments and sharing calibration data. This collection has been continually updated since 1991. Many colleagues have indicated that they are using the software in their labs. Documentation is in the source files themselves. Many of the routines are Mac-specific, but some very useful routines, e.g. the luminance-control, statistics, maximum-likelihood fitting algorithms, and the runtime interpreter are written in Standard C and will work on any computer. Those wishing to acknowledge use of the VideoToolbox software might cite:
Pelli, D. G. and Zhang, L. (1991) Accurate control of contrast on microcomputer displays. Vision Research, 31, 1337-1350. Reprints are available.
AVAILABILITY:
The VideoToolbox software is continually updated. To get the latest version just download "video-toolbox" electronically from a public archive:
Log in as "anonymous"; any password will do. If you can't do ftp, you can request a file by email; for instructions send a query to Info-Mac-Request@sumex-aim.stanford.edu. (Or, if you're a member of CompuServe, download VIDEOT.SEA from Library 4 "C and Pascal" in the MacDev forum.) If you aren't electronically connected, send me your postal address, and I'll mail you a disk. To get future versions automatically, just send me your email address. Each time I post a new version of the VideoToolbox to the Info-Mac Archives, I email a copy to everyone on the subscription list. [The ISR Video Attenuator is a commercial product. Ordering instructions are in the "Video attenuator" file. I have no financial involvement in the ISR Video Attenuator.]
AUTHORS:
Adobe (ATMInterface.c and ATMInterface.h)
Apple (IsCmdPeriod.c,MoveMouse.c,TrapAvailable.c, Zoom.c)
Kevin Bell (PatchExitToShell in Timer.c)
Philipp Biermann ("Multisync Sense Pins.note")
David Brainard (a dozen routines in Assign.c, one in GDOpenWindow.c, GetTimeDateString.c, PeekTimer in Timer.c)
EJ Chichilniski (SetFileInfo.c)
Raynald Comtois (SetEntriesQuickly.c)
Steve Coy (PatchExitToShell in Timer.c)
Bart Farell (several routines in SetOnePixel.c and SetPixelsQuickly.c)
Bill Haake (SetEntriesQuickly.c)
Bill Hofmann (PatchExitToShell in Timer.c)
Mike Kahl (CopyQuickDrawGlobals.c, kbhit.c)
Joseph Laffey (GetVersionString.c)
Peter Lennie (SetEntriesQuickly.c)
J.N. Little & jmb (ReadMATLABFile.c)
Jamie R. McCarthy (IsCmdPeriod.c)
Izumi Ozhawa (CVNetConvert in the Utilities folder)
Denis Pelli (most of the routines)
SPLAsh Resources (HideMenuBar.c, SetMouse.c)
Dave Radcliffe (FlushCacheRange.c)
Evan Relkin (kbhit.c)
Mike Schechter (PixMapToPICT.c)
Preeti Verghese (GetVoltage.c)
Detailed attribution appears in each file. Please advise of any errors or omissions.
METROWERKS CODEWARRIOR C:
All the VideoToolbox demos now compile and run as native code on both 68k and Power PC Macs, using CodeWarrior C version CW4.5. See the VideoToolbox "Advice" document for comments and ordering information.
THINK C:
If you don't have a compiler, I'd suggest buying Metrowerks CodeWarrior C. If you use THINK C, I suggest that you upgrade to the latest version, currently 7.04. (The upgrade from version 6 is free.) You cannot use the VideoToolbox with any version of THINK C older than 5. See the VideoToolbox "Advice" document for comments and ordering information.
MATLAB:
David Brainard (brainard@condor.psych.ucsb.edu) has created interface files that make it easy to use the VideoToolbox from within MATLAB. They're available by anonymous ftp. Also see VideoToolboxMATLAB.c in VideoToolboxSources.
You'll need to recreate the pre-compiled header; see VideoToolbox.c. If you get link errors when rebuilding your re-existing project, it is likely that you'll need to add "Nan.c" and MacMemory.c to your project.
GETTING STARTED:
Try the demos: Sandstorm, Grating, FlickeringGrating, Filter, and TimeVideo. TimeVideo times all of your displays, telling you how quickly you can show movies and do lookup table animation. Read "Video synch" and "Advice".
You'll want the VideoToolboxSources folder to be included in your project's search path. Don't copy source files to your projects; just "Add" them using your compiler's Source or Project menu. That will make it easy to update the VideoToolbox. In Metrowerks you'll add VideoToolbox to each of your project's "Access paths" preferences. For THINK C, the simplest approach is to place the entire VideoToolbox inside your THINK C folder. (The Symantec documents say this is a no-no, but it works fine. If you have THINK C 7 then an equally good alternative is to place the VideoToolbox folder outside the THINK C folder--or to shield the folder from the search path by putting parentheses around it "(VideoToolbox)"--and to place an alias to the VideoToolboxSources folder inside the THINK C Aliases folder.)
Follow the instructions in VideoToolbox.c to precompile VideoToolbox.h to recreate the precompiled header or headers that you'll need, since they must be produced by your version of the compiler. (If you're producing an external code resource for MATLAB then use VideoToolboxMATLAB.c instead.) Put all the pre-compiled headers in "VideoToolbox:VideoToolboxSources: Precompiled headers". Here is the naming convention that I use:
"VideoToolbox.pre" = THINK C, 68k, 2-byte int, "universal" floating point (works with or without 8881 fpu).
"VideoToolbox.68k.4i.881.pre" = CodeWarrior, 68k, 4-byte int, 12-byte double for 8881.
"VideoToolbox.68k.4i.pre" = CodeWarrior, 68k, 4-byte int, 10-byte double for no fpu.
"VideoToolbox.ppc.pre" = CodeWarrior, PowerPC, necessarily 4-byte int and 8-byte double.
Note that all the compilers consider it the user's responsibility (why?) to ensure that the current compiler settings are consistent with those of the pre-compiled header and the object code libraries (e.g. "ANSI" in THINK C or "ANSI (4i/881) C.68k" in CodeWarrior). It is very easy to forget this rule, leading to mysterious crashes. Therefore it is highly recommended that you call the VideoToolbox Require() once at the beginning of your program because it explicitly checks for the compatibility of the assumed size of int and double among the three components, producing a helpful error message instead of a mysterious crash if you goof.
The VideoToolbox contains up-to-date project documents for current versions of the compilers (names ending in ".π" for THINK C 7 and ".µ" for Metrowerks CodeWarrior CW4.5). Users of older versions of the compilers (e.g. THINK C 5 and 6) unfortunately can't use the new projects (complain to the authors of the compilers, who seem to have no compunction about changing the project format every time they release a new version), so I have included old versions of the project files (".π5" for THINK C 5). However, be warned that we have no way to update these projects, and they all will require a bit of work to bring up-to-date, to reflect new or renamed source files. Basically you just need to respond to "file not found" messages from the compiler and "unresolved external references" messages from the linker by removing nonexistent source files from the project and adding new ones.
All the programs that do accurate luminance control use the monitor-calibration data stored in LuminanceRecord1.h (the number is a screen number, similar--but not identical--to the number that appears in the Monitors control panel). These calibration files describe one of my monitors (an Apple High-Resolution Monochrome), and, naturally, before doing any serious data collection you should create new files that describe your own monitors. Use the CalibrateLuminance program and a photometer.
NUMERICAL RECIPES IN C:
A few programs in the VideoToolbox (CalibrateLuminance.c, PsychometricFit.c, and Quick3) use the (very handy) Numerical Recipes software and book. Required changes to these routines are described in the "Improve Numerical Recipes" document in the Notes folder. I have included pre-compiled CalibrateLuminance and Quick3 applications for users that don't have the Numerical Recipes. The Numerical Recipes C Set for Macintosh (main book, example book, and disk) costs $90 from:
Cambridge University Press
Orders Department
110 Midland Avenue
Port Chester, NY 10573
1-(800)-227-0247
<SANE.h> IS DEAD. LONG LIVE <fp.h>:
In going to the PowerPC, Apple wisely decided to drop <SANE.h>, i.e. their Standard Apple Numerics Environment routines, in favor of <fp.h>, i.e. the Floating-Point C Extensions (FPCE) proposed by the Numerical C Extensions Group (NCEG). SANE was uselessly slow anyway since it was tied to 10-byte doubles, whereas the 68881 floating point chip used 12-byte doubles. The <fp.h> extensions are very welcome, providing some handy math functions and providing standard ways of producing and testing for NAN and INF. <fp.h> provides standard routines very similar to the VideoToolbox routines IsNan and IsFinite. At the moment (October '94), <fp.h> routines are fully implemented only on the PowerPC--only a few are available on 68k--but Apple has promised to fully implement the <fp.h> routines on 68k machines as well. I will continue using my VideoToolbox routines until both PPC and 68k are supported by fp.h, then I'll redefine the VideoToolbox routines to just use the <fp.h> routines. If you have any programs that use <SANE.h>, you should think about using <fp.h> instead. Don't explicitly include <fp.h>; it's brought in automatically by <math.h>.
PORTABILITY:
Various issues to do with porting programs among different computers and compilers are discussed in the Portability document.
BUGS & SUGGESTIONS:
It's unlikely that you'll find any bugs, but if you do, please send me email so we can fix 'em. Suggestions and code donations (i.e. C routines to be included in the VideoToolbox, possibly in modified form, with full attribution) are warmly appreciated.
denis_pelli@isr.syr.edu
NOT MULTIFINDER FRIENDLY:
Walt Makous writes, "I ran Sandstorm by clicking on the icon for the application, interrupted it by clicking outside the window, and then resumed it by clicking on the window again. This locks the keyboard so that the only way I can get back control is by using the programmer's switch." REPLY: Alas, I've never had any need to write polite applications that gracefully share the computer with other applications. Experiments always seem to deserve hogging it all. The Sandstorm demo allows you to invoke other applications, because it doesn't obscure the whole window, but it doesn't act like a good citizen in paying attention to the messages it gets from the Finder about what happened. (I would go ahead and make the demos multifinder-friendly if I knew how, but it has seemed worth learning just for the sake of the demos.)
COPYBITS, COPYBITSQUICKLY, and COPYWINDOWS:
CopyBits is one of Apple's more impressive efforts. It's powerful and fast. For my purposes its only drawback is that I haven't always been able to prevent it from doing color translations. So I wrote CopyBitsQuickly to copy images without color translations. (A long time ago CopyBits used to be slow, but that's history. At present CopyBitsQuickly is approximately the same speed as CopyBits.) However, both CopyBits and CopyBitsQuickly require you to supply pixmap pointers, which can be a nuisance. These days, our programs use windows (created by GDOpenWindow) and GWorlds (which are really offscreen windows). Getting the pixmap's pointer from the guts of the window is straightforward but messy (see BitMapPtr in GDOpenWindow.c). Now you don't have to bother. Just call CopyWindows.c. Its first two arguments are the source and destination windows. The rest of the arguments are like those for CopyBits or CopyBitsQuickly. It makes your programs much easier to write, to read, and probably more robust because there are a lot of little fragile assumptions that people often make in calling CopyBits, which CopyWindows takes care of for you. Look at the demo NoiseVBL.c.
BLOCKMOVEDATA:
BlockMoveData is a new (as of System Update 3.0 to System 7.1) variant of BlockMove that omits cache flushing. Calling BlockMoveData() on earlier versions of the operating system will invoke plain old BlockMove(). BlockMove is coded in each computer's ROM to implement the fastest possible move. E.g. it uses the MOVE16 instruction on the 68040 processor. It may be faster than the generic code that most C compilers produce. When the Quadra's were released, Apple added code to the BlockMove trap to flush the instruction cache each time BlockMove was called, just in case the move was copying instructions that were in the cache. However, flushing the cache everytime you call BlockMove sacrifices the speed benefit of the cache, making it less advantageous to call BlockMove. In System Update 3.0 Apple finally gave developers a way of telling BlockMove not to flush the cache. You call BlockMoveData instead. However, if run on computers lacking System Update 3.0 the flag bit distinguishing BlockMoveData from the old BlockMove will be ignored and the cache will be flushed, which will slow you down. BlockMoveData() is defined in Apple's Memory.h in Apple's new Universal Header files, but is not defined in pre-Universal header files. VideoToolbox.h tests for that case and, if necessary, defines BlockMoveData, so that you may use it freely.
68040:
Peter Lennie writes (6/23/93): "On the latest developers CD [June? '93] there's a note about the Quadra's use of a trap to emulate the FINTRZ instruction, which isn't built into the 68040. This instruction is called commonly in the code generated by THINK C [5, when FPU use is enabled], and for me it became an issue in the loops that recalculate lookup tables during chromatic flicker. By rewriting the loop to avoid that instruction (using a small function supplied on the CD) I reduced the time it took to recalculate --as opposed to write-- the tables from 16msec to 1.6 msec." [Does anyone know whether this concern is still applicable to the current version: 7.04? I don't use the Quadra. dgp]
DISCLAIMER (included at the request of the MacPsych archive):
The VideoToolbox is provided "as is" without warranty of any kind. Denis Pelli, Syracuse University, SCiP, the operators of MacPsych, and St. Olaf College make no claims concerning the accuracy or correctness of the computer code contained in, or the results of the use of VideoToolbox. The entire risk as to the results and performance of VideoToolbox is assumed by you. If the VideoToolbox is defective you, and not Denis Pelli, Syracuse University, SCiP, the operators of MacPsych, or St. Olaf College assume the entire cost of all necessary servicing, repair or correction.
